feat(scoring): explain score scenario previews for miners#1935
Closed
andriypolanski wants to merge 2 commits into
Closed
feat(scoring): explain score scenario previews for miners#1935andriypolanski wants to merge 2 commits into
andriypolanski wants to merge 2 commits into
Conversation
andriypolanski
changed the title
📄 Knowledge review✏️ Suggested updates1 page suggestion needs review.
📝 MCP & Agent Integration@@ -10,18 +10,18 @@
The **Model Context Protocol (MCP)** is a standardized interface that allows coding agents and AI tools to connect with external data sources and services in a structured, tool-call-based way. Rather than ad-hoc API integrations, MCP defines a common schema for tool registration, input validation, and structured JSON responses — enabling any MCP-compatible client (Claude Desktop, Cursor, Codex, etc.) to interact with a server like Gittensory without custom wiring.
-`@jsonbored/gittensory-mcp` implements MCP using `@modelcontextprotocol/sdk` v1.29.0 [[4]](https://app.dosu.dev/7d8810aa-91c6-4074-849b-92fab65de734/documents/09d20768-c6a2-4ac0-9000-4395a9728dc9#L323-L334). It registers 21 tools across five capability areas and exposes them over standard stdio transport, making Gittensory's intelligence layer accessible to any MCP-compatible client.
+`@jsonbored/gittensory-mcp` implements MCP using `@modelcontextprotocol/sdk` v1.29.0 [[4]](https://app.dosu.dev/7d8810aa-91c6-4074-849b-92fab65de734/documents/09d20768-c6a2-4ac0-9000-4395a9728dc9#L323-L334). It registers 22 tools across five capability areas and exposes them over standard stdio transport, making Gittensory's intelligence layer accessible to any MCP-compatible client.
### What it provides
The package exposes two surfaces for different audiences:
-- **21 MCP tools** — structured tool definitions callable by AI agents via the MCP protocol, covering repo intelligence, PR preflight, scoring, contributor decisions, current-branch analysis, and agent planning [[5]](https://app.dosu.dev/7d8810aa-91c6-4074-849b-92fab65de734/documents/09d20768-c6a2-4ac0-9000-4395a9728dc9#L92-L98)
+- **22 MCP tools** — structured tool definitions callable by AI agents via the MCP protocol, covering repo intelligence, PR preflight, scoring, contributor decisions, current-branch analysis, and agent planning [[5]](https://app.dosu.dev/7d8810aa-91c6-4074-849b-92fab65de734/documents/09d20768-c6a2-4ac0-9000-4395a9728dc9#L92-L98)
- **17 CLI commands** — human-friendly equivalents of the same capabilities, usable directly from a terminal or CI script
It is designed for three audiences:
-- **Miners** — use the package to plan work, preflight branches before opening PRs, and prepare public-safe PR packets
+- **Miners** — use the package to plan work, preflight branches before opening PRs, prepare public-safe PR packets, and understand score improvement paths through scenario explanations
- **Coding agents** — consume deterministic tool schemas to gain structured Gittensor context without requiring source code upload
- **Maintainers** — access private reviewability context and contributor decision packs through the API
@@ -186,7 +186,7 @@
gittensory-mcp --stdio
```
-This starts an `McpServer` named `gittensory-local` that communicates via `StdioServerTransport` — reading JSON-RPC messages from stdin and writing responses to stdout [[14]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L151-L154) [[15]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L459). The server registers all 21 MCP tools and remains alive until the client process exits.
+This starts an `McpServer` named `gittensory-local` that communicates via `StdioServerTransport` — reading JSON-RPC messages from stdin and writing responses to stdout [[14]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L151-L154) [[15]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L459). The server registers all 22 MCP tools and remains alive until the client process exits.
The `--stdio` flag is what MCP clients use to spawn and communicate with the server. From the client's perspective, Gittensory appears as a local process that accepts tool calls and returns structured JSON results.
@@ -217,7 +217,7 @@
## What Context It Exposes to Agents
-The 21 MCP tools are organized into five capability categories. Together they give agents a complete picture of contribution health — from raw repo signals to scored, ranked next actions — without requiring source code upload.
+The 22 MCP tools are organized into five capability categories. Together they give agents a complete picture of contribution health — from raw repo signals to scored, ranked next actions — without requiring source code upload.
### Repo Intelligence
@@ -235,6 +235,7 @@
| `gittensory_preflight_pr` | Validates planned PR metadata (title, body, labels, changed files, linked issues, tests) against lane, duplicate, linked-issue, test, and queue signals. Returns a preflight status and a list of findings [[21]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L168-L175) |
| `gittensory_preflight_local_diff` | Inspects the local git diff metadata and runs the same preflight checks — without uploading source contents. Collects changed files, line counts, and test files locally [[22]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L177-L201) |
| `gittensory_preview_local_pr_score` | Requests a private scoring preview for the local diff. Accepts optional score overrides (sourceTokenScore, totalTokenScore, sourceLines) and projected contributor state. No source upload [[23]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L212-L219) |
+| `gittensory_explain_score_scenarios` | Explain private score-preview what-if scenarios and gate deltas with ranked cleanup paths. Login and repo scoped; no new computation beyond the preview projection. Returns repoFullName, scoreabilityStatus, effectiveEstimatedScore, headline, scenarios (array of what-if scenario explanations), gateDeltaNarratives (explanations of multiplier stack changes), and recommendedPath (suggested cleanup strategy). Provides human-readable explanations of the six scenario projections (cleanGates, afterPendingMerges, afterApprovedPrsMerge, afterStalePrsClose, linkedIssueFixed, bestReasonableCase) and gate deltas from score preview, helping users understand cleanup priorities and score improvement paths |
| `gittensory_compare_pr_variants` | Compares private scoring previews across up to 10 metadata variants. Results are sorted by estimated score, making it easy to identify the strongest approach [[24]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L243-L255) |
### Contributor Decisions
@@ -630,7 +631,7 @@
### MCP Tools Reference
-All 21 tools use Zod-validated input schemas [[53]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L28-L144) and return a structured response containing a human-readable `summary` string and a JSON `data` object.
+All 22 tools use Zod-validated input schemas [[53]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L28-L144) and return a structured response containing a human-readable `summary` string and a JSON `data` object.
#### Category 1: Repo Intelligence
@@ -677,6 +678,13 @@
- **Input:** All fields from `localDiffShape` plus optional `sourceTokenScore`, `totalTokenScore`, `sourceLines`, `credibility`, `projectedCredibility`, PR state fields, `scenarioNotes`, and `branchEligibility` (object with `status`, `source`, `reason`, `checkedAt`, `stale`)
- **Output:** Score estimate with scenario breakdowns, setup guidance if scorer is missing
- **Use case:** Get a private score estimate before opening a PR [[23]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L212-L219)
+
+**`gittensory_explain_score_scenarios`**
+
+- **Purpose:** Explain private score-preview what-if scenarios and gate deltas with ranked cleanup paths
+- **Input:** Same as `gittensory_preview_local_pr_score` (contributorLogin, repoFullName, prNumber, etc.)
+- **Output:** `repoFullName`, `scoreabilityStatus`, `effectiveEstimatedScore`, `headline`, `scenarios` (array of what-if scenario explanations), `gateDeltaNarratives` (explanations of multiplier stack changes), `recommendedPath` (suggested cleanup strategy)
+- **Use case:** Provides human-readable explanations of the six scenario projections (`cleanGates`, `afterPendingMerges`, `afterApprovedPrsMerge`, `afterStalePrsClose`, `linkedIssueFixed`, `bestReasonableCase`) and gate deltas from score preview, helping users understand cleanup priorities and score improvement paths
**`gittensory_compare_pr_variants`**
|
|
Warning 🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨 ⏸️ Gittensory review result - manual review recommendedReview updated: 2026-07-01 07:00:10 UTC
⏸️ Suggested Action - Manual Review
Review summary Nits — 7 non-blocking
Review context
Contributor next steps
Signal definitions
🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed 💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →. Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.
|
loopover-orb
Bot
added
gittensor
gittensor:feature
JSONbored
added this to the
M3.5 — Agent Layer Phase 2 (maintainer auto-maintain) milestone
This was referenced Jul 1, 2026
Merged
JSONbored
approved these changes
Jul 1, 2026
JSONbored
left a comment
JSONbored
left a comment
Owner
There was a problem hiding this comment.
Fix these minor issues before I can approve:
The most notable weakness is that some response schema fields are looser than the TypeScript service contract.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
buildScorePreview(src/scoring/preview.ts) already emits rich what-if scenario previews (scenarioPreviews:cleanGates,afterPendingMerges,afterApprovedPrsMerge,afterStalePrsClose,linkedIssueFixed,bestReasonableCase) and gate deltas (gateDeltas) comparing current vs projected multiplier stacks. Miners consuminggittensory_preview_local_pr_scoreget raw structured data, andgittensory_explain_score_breakdownexplains per-multiplier levers — but no tool narrates which scenario path unlocks scoreability or ranks the highest-leverage cleanup sequence (land pending merges vs fix linked issue vs clear open-PR pressure).Contributors stuck at
conditionally_scoreablesee numeric deltas in JSON without plain-English guidance on the best next state transition.What this adds
A pure projection service
explainScoreScenariosmirroringexplainScoreBreakdown:currentpreview: name, source (github_observed/user_supplied/gittensory_projection), sanitized assumptions, scoreability band (blocked→conditionally_scoreable→scoreable), and a one-line delta vs current.ScoreGateDeltainto actionable copy (which gate moves, what changes, estimated direction — without leaking forbidden reward language).afterStalePrsCloseis the top unlock).gittensory_explain_score_scenariosand matching API route — same input shape asgittensory_explain_score_breakdown/ score preview.Purely additive explanation over already-computed preview fields; no scoring behavior change.
Files touched (estimated)
src/services/score-scenario-explain.tsexplainScoreScenarios, scenario ranking, gate-delta narrativessrc/mcp/server.tsgittensory_explain_score_scenarios+ output schemasrc/api/routes.tsPOST /v1/repos/:owner/:repo/score/scenario-explanation(or sibling to existing breakdown route)src/openapi/schemas.tsScoreScenarioExplanationschemaapps/gittensory-ui/public/openapi.jsonnpm run ui:openapitest/unit/score-scenario-explain.test.tstest/unit/mcp-output-schemas.test.tstest/integration/api.test.tsValidation
git diff --checknpm run actionlintnpm run typechecknpm run test:coverage— aim for 100% statements/branches on changed lines insrc/services/score-scenario-explain.tsnpm run test:workersnpm run build:mcpnpm run test:mcp-packnpm run ui:openapi:checknpm run ui:lintnpm run ui:typechecknpm run ui:buildnpm audit --audit-level=moderateTargeted test run:
npx vitest run test/unit/score-scenario-explain.test.ts test/unit/mcp-output-schemas.test.ts --coverage --coverage.include='src/services/score-scenario-explain.ts'Notes
Analogues to imitate end-to-end:
explainScoreBreakdowninsrc/services/score-breakdown.ts,renderPublicScenarioSummary/OPTION_NEXT_STEPSinsrc/scenarios/scenario-summary.ts, and MCP registration forgittensory_explain_score_breakdowninsrc/mcp/server.ts.